{
    title:  "Compiling Sources",
    crumbs: [
        { "Developer's Guide": 'index.html' },
    ],
}
        <h2>Compiling Sources</h2>
        <p>MakeMe compiles source files by building library or executable targets that specify the sources to be compiled. 
        <p>For example, this target will compile the sources in the current directory and create a shared library containing
        the compiled objects.</p>
<pre class="ui code segment">
targets {
    libname: {
        type: 'lib',
        sources: '*.c',
    },
}
</pre>
        <p>MakeMe expands the <em>sources</em> property and creates objects targets at run-time for each of the corresponding sources.
        <p>MakeMe also creates targets for any include files referenced by the sources.  If the source file is updated, it will
        be recompiled and library rebuilt when MakeMe is next run. If any of the included headers are updated, the source file
        and library will similarly be rebuilt.</p>
        <p>Source targets are related to their library target via a <em>depends</em> property. The 
        target that specified the sources (in this example, the library) will depend on the sources. The various source
        targets will depend on their include header targets. When building, MakeMe will recursively consider the dependant
        targets and rebuild any that are out-of-date.</p>
        <p>Any target can specify a list of sources. Typically, this will be libraries and executables, but any 
        target can specify sources. For completeness, here is an executable target.</p>
<pre class="ui code segment">
myProgram: {
    type: 'exe',
    sources: '*.c',
},
</pre>
        <a name="selecting"></a>
        <h2>Selecting Source Files</h2>
        <p>The <em>sources</em> property may be set to a regular expression, a string or an array of either. 
        For example: </p>
<pre class="ui code segment">
sources: /view-.*\.c|image.*\.c/,
</pre>
        <p>This will select any C source files starting with 'view-' or 'image' in the current directory.</p>
<pre class="ui code segment">
sources: ['*.c', '*.cpp'],
</pre>
        <p>This will select C and C++ source files in the current directory.</p>
<pre class="ui code segment">
sources: '**.c',
</pre>
        <p>This will select C source files in the current directory or in any sub-directory below.</p>
        <p>Multiple sources properties can be specified by using an array of strings.</p>
<pre class="ui code segment">
source: ['*.c', '*.cpp' ],
</pre>
        <p>This is useful when the sources to build may be specified in more than one MakeMe file.</p>
        <h3>Excluding Items</h3>
        <p>You can exclude specific items from the sources list. Similar to the sources property, the 
        <em>exclude</em> property can be set to a regular expression, a string or an array of either. Once
        the list of sources is built from the sources property, each qualifying source file is checked to see if
        it should be excluded. The exclusion match is performed on the entire source file name.</p>
        <pre class="ui code segment">
sources: '**.c',
<b>exclude: /\/test$|\/demo$'</b>,
</pre>
        <p>This will exclude C files in the test and demo directories. If using regular expressions, make sure you 
        include a leading '\/' and trailing '$' if you want to match a directory basename.</p>
        <a name="headers"></a>
        <h2>Headers</h2>
        <p>MakeMe, by convention, copies declared headers to the platform <em>OS-ARCH-PROFILE/inc</em> directory. This is
        so that headers can be easily resolved when compiling by a single <em>-I</em> compiler flag. This is not required,
        but certainly recommended. You can specify headers to export to the platform directory via 
        the <em>headers</em> property. For example:
        <pre class="ui code segment">
libname: {
    type: 'lib',
    sources: '*.c',
    headers: [ '*.h' ],
}
</pre>
        <p>This will create targets at run-time for all headers in the current directory. These targets will copy the
        headers (if modified) to the <em>inc</em> directory for the platform. The standard MakeMe compile rules will then
        resolve the headers from the inc directory.</p>
        <a name="resources"></a>
        <h2>Resources</h2>
        <p>MakeMe can compile Windows resources by specifying them in a <em>resources</em> property list.
        For example:
        <pre class="ui code segment">
appwebMonitor: {
    enable: "me.platform.like == 'windows'",
    type: 'exe',
    rule: 'gui',
    depends: [ 'libappweb' ],
    sources: [ 'windows/*.c' ],
    headers: [ 'windows/*.h' ],                                                                    
    libraries: [ 'shell32.lib' ],
    <b>resources: [ 'windows/appwebMonitor.rc' ]</b>,
},
</pre>
        <p>This will use the Windows resource compiler <em>rc</em> to compile the resource and then link into the
        executable.</p>
        <a name="options"></a>
        <h2>Compiler Options</h2>
        <p>MakeMe has builtin defaults for the various compiler and linker command line formats. The include properties 
        for include directories, compiler options, compiler pre-processor definitions, link libraries, paths and options. 
        These properties are inherited by
        all targets who can use, augment or modify these defaults if required. Typically, the defaults are sufficient,
        but they can be modified, augmented or delete on a per-target basis.</p>
        <p>For example, to add additional switches, libraries and other compilation options:
<pre class="ui code segment">
mylib: {
    '+includes': [
        "macosx-x64-debug/inc",
    ],
    '+compiler': [
        "-fomit-frame-pointer",
    ],
    '+defines': [
        "ENABLE_TURBO_MODE",
    ],
    '+libraries': [
        "edit",
    ],
    '+libpaths': [
        "headers",
    ],
    '+linker': [
        "-Wl,-rpath,/opt/lib",
    ],
},
</pre>
        <p>Here are the supported properties</p>
        <table title="properties" class="full">
            <thead>
                <tr><th>Property</th><th>Purpose</th>
            </thead>
            <tbody>
                <tr><td>includes</td><td>Directories to search for headers</td>
                <tr><td>compiler</td><td>Compiler options</td>
                <tr><td>defines</td><td>Compiler pre-processor defines</td>
                <tr><td>libraries</td><td>Libraries to link with when linking</td>
                <tr><td>libpaths</td><td>Directories to search for libraries</td>
                <tr><td>linker</td><td>Linker flags</td>
            </tbody>
        </table>
        <p>Use a "<em>+</em>"" prefix when defining array values. This adds the values to the existing property set. Use
        <em>-</em> to remove a value from the existing definition. Use a an "<em>=</em>" prefix to replace existing values. </p>
        <p>Note that the default link phase rules use the compiler and not the linker to create executables. As such,
        linker flags must be prefixed to pass through to the linker. Also note that many compiler and linker flags are
        platform specific and thus not-portable. Fortunately, MakeMe portably defines most common compiler and linker
        flags for you. If you need to portably modify these flags, you will need to use some scripting.</p>
        <h3>Target Scripting</h3>
        <p>Targets can run scripts at various stages in the build life cycle. These scripts run in response to build events.
        Defining a script to run in response to the <em>precompile</em> event will enable us to modify the
        compiler properties before the target is build. For example:</p>
        <pre class="ui code segment">scripts: {
    precompile: "
        if (me.platform.os == 'windows') {
            me.target.compiler.push('-GF -Wp64')
        }
    ",
},
</pre>
        <p>For detailed information on scripting, please see <a href="../ref/events.html">MakeMe Events</a> and
        <a href="scripts.html">MakeMe Scripting</a>.</p>
        <a name="inheriting"></a>
        <h2>Inheriting Defaults</h2>
        <p>Every target inherits default properties from the <em>defaults</em> and <em>internal</em> property collections.
        The default collection is global across the project. The internal collection is local to the current MakeMe file.</p>
        <p>MakeMe defines the initial compiler properties as required for the current platform operating system and CPU 
        architecture. However, you can override the default properties so that all targets inherit your customizations. For
        example: <pre class="ui code segment">
defaults: {
    '+defines': [ 'ENABLE_DIRECT_X' ],
},
</pre>
        <h3>Private Inheritance</h3>
        <p>Similar to the defaults collection, you can specify properties that are inherited only by targets in
        the same MakeMe file. To do this, create an <em>internal</em> collection.
        <pre class="ui code segment">
internal: {
    libraries: [ 'pam', 'z' ],
},
</pre>
        <h2>Explicit Inheritance</h2>
        <p>Sometimes you have a some settings that must be inherited by a subset of targets that are not in the same
        MakeMe file. MakeMe allows a target to specify a collection of settings from which to inherit via the
        <em>inherit</em> property. For example:
<pre class="ui code segment">
<b>'shared-settings': {
    '+defines': [ 'NUMBER=42' ],
},</b></pre>
        <p>These shared settings can be in any MakeMe file.</p>
<pre class="ui code segment">
rocket {
    <b>inherit: ['shared-settings']</b>,
    type: 'exe'
    sources: '*.c',
},
</pre>
        <p>In this manner, specific targets can nominate the group of settings form which they wish to inherit.</p>
        <h2>Compiler Rules</h2>
        <p>MakeMe defines compiler command templates to use for compiling, linking and other tasks. These templates are
        defined in the the <em>rules</em> property collection. These templates are unique for each supported platform
        as they depend on the local compiler.</p>
        <p>You should rarely need to modify these templates, but like the rest of MakeMe, you can modify them if you need to. 
        Rules use as their property name, the desired transition. This is of the form: <em>'FROM-&gt;TO'</em> For example,
        to compile a <em>.c</em> file into a <em>.o</em>, the rule name would be <em>'.c-&gt;.o'</em>
        For example:</p>
<pre class="ui code segment">
rules: {
    'c-&gt;o': '${targets.compiler.path} -c -o ${OUT} ${CFLAGS} ${DEFINES} ${INCLUDES} ${IN}',
},
</pre>
        <p>The various <em>${token}</em> values are expanded by MakeMe using the compiler properties.
        The ${OUT} token is set to the target destination path. The ${IN} token is set to the name of the file to 
        compile.</p>
        <h2>Examples</h2>
        <p>Here is an actual example from the Ejscript project that builds the ejs library:</p>
        <pre class="ui code segment">
libejs: {
    type: 'lib',
    headers: [ 'slots/*.h', '*.h' ],
    sources: [
        'compiler/*.c',
        'core/src/*.c',
        'vm/*.c'
    ],
    depends: [ 'libhttp' ],
},
</pre>
        <p>To learn more, read about <a href="libraries.html">Creating Libraries</a>.</p>
